home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / exampleCode / GLX / DBglxwidget / README < prev   
Encoding:
Text File  |  1994-08-02  |  8.9 KB  |  251 lines
  1. /*****************************************************************************/
  2. /* NEW GLX WIDGET DESCRIPTION                             */
  3. /* Date:    11-12-92                              */
  4. /* Revision by:    Ed Millard and Chris Carlson                     */
  5. /*****************************************************************************/
  6.  
  7. This directory contains source for a new version of the SGI GLX mixed
  8. mode Xt widget (GlxDraw) and the GLX mixed mode Motif widget
  9. (GlxMDraw).  The Motif widget is identical to the Xt version except
  10. with the addition of the Primitive base class and the Motif interface.
  11. These widgets, like their predecessor GlxDraw and GlxMDraw widgets,
  12. allows the use of GL within X windows with Xt and Motif applications.
  13. This new version allows switching between single and double buffering
  14. in the GL window by using XtSetValues.  Its intent is to reduce the
  15. application programming required to use single and double buffer in a
  16. mixed mode application.
  17.  
  18. REQUIREMENTS
  19. ------------
  20.  
  21. Currently, these widgets have only been designed to work under X11R4
  22. (IRIX 4.0.x).  We are working on getting them to work for X11R5 but it
  23. isn't finished yet.
  24.  
  25. DEMO MAKE
  26. ---------
  27.  
  28. Run make in this directory to rebuild the library libsgiw.a,
  29. containing both the GlxDraw and GlxMDraw widgets.  To build overlay.c,
  30. a small test program, demonstrating the widget, run 'make overlay'.
  31.  
  32. APPLICATION MAKE
  33. ----------------
  34.  
  35. To use this new widget you must include the "GlxDraw.h" (or
  36. "GlxMDraw.h" for Motif) from this directory and not the one in
  37. /usr/include/X11/Xirisw.
  38.  
  39. You must link with GlxDraw.o or GlxMDraw.o (for Xt version or Motif
  40. version respectively) or the libsgiw.a library from this directory
  41. instead of libXirisw.a.
  42.  
  43. USAGE
  44. -----
  45.  
  46. The example code below is provided to demonstrate how to create a
  47. Motif GL widget.  Similar code can be used to create the Xt version.
  48.  
  49. GLXconfig structure:
  50. --------------------
  51. The first step in creating a mixed-model widget is creating a
  52. GLXconfig structure describing the type of GL window you need.  This
  53. structure should describe the normal window and any overlay, underlay
  54. or popup windows that will be required.
  55.  
  56. NOTE: When requesting both double and single buffering, you MUST
  57. request a single buffered window in the GLXconfig structure.  Since
  58. the double buffered window will be a child of the single buffered
  59. window, it is important that the parent have more bitplanes than the
  60. child.
  61.  
  62. Here is an example of defining a GLXconfig structure:
  63.  
  64.     static GLXconfig glxConfig [] = {
  65.         { GLX_NORMAL, GLX_DOUBLE, FALSE },
  66.         { GLX_NORMAL, GLX_RGB, FALSE },
  67.         { GLX_OVERLAY, GLX_BUFSIZE, 2 },
  68.         { 0, 0, 0 }
  69.     };
  70.  
  71. This GLXconfig structure requests a single buffered window, running in
  72. colormap mode with an overlay window having a depth of 2.
  73.  
  74. Setting resources:
  75. ------------------
  76. The following code excerpt shows how to request a GLX widget that is
  77. single buffered (default window), colormapped and has overlay planes.
  78. It also enables the double buffered window.  It assumes the GLXconfig
  79. structure shown above.
  80.  
  81.     n = 0;
  82.     XtSetArg (args[n], GlxNglxConfig, glxConfig); n++;
  83.     XtSetArg (args[n], GlxNuseOverlay, TRUE); n++;
  84.     XtSetArg (args[n], GlxNprovideSingleBuffer, TRUE); n++;
  85.     glw = XtCreateManagedWidget("glwidget", glxMDrawWidgetClass,
  86.                                     frame, args, n);
  87.  
  88. The first resource defines the GLXconfig structure to use.  The second
  89. resource requests the overlay planes.  The third resource indicates we
  90. also want the double buffered window.
  91.  
  92. Switching single/double buffering:
  93. ----------------------------------
  94. To switch to double buffer mode:
  95.  
  96.         n = 0;
  97.             XtSetArg (args[n], GlxNsingleBuffer, FALSE); n++;
  98.             XtSetValues (w, args, n);
  99.  
  100. To switch to single buffer mode:
  101.  
  102.         n = 0;
  103.             XtSetArg (args[n], GlxNsingleBuffer, TRUE); n++;
  104.             XtSetValues (w, args, n);
  105.  
  106.  
  107. DEMO PROGRAM USAGE
  108. ------------------
  109.  
  110. The program overlay.c is a modification of the program overlay.c provided
  111. in 4Dgifts.  If the symbol USE_NEW_WIDGET is not defined, it should
  112. work exactly like overlay.c.  With the symbol defined, the mouse
  113. buttons work as follows:
  114.  
  115.     Left    - Move the car in the main window
  116.     Middle    - Selects single buffering
  117.     Right    - Selects double buffering
  118.  
  119. The house is in the overlay planes.  The car is drawn in the normal
  120. planes and will flicker in single buffer mode.
  121.  
  122. MORE WORK REQUIRED
  123. ------------------
  124.  
  125. When switching from one buffering mode to the other, much of the GL
  126. context set up in the old window is saved and restored into the new
  127. window.  (Lighting, materials and textures must be done by the
  128. application.)  It would be nice to be able to have a resource that
  129. indicates when this operation must be done so it isn't done every
  130. time.
  131.  
  132. BUGS
  133. ----
  134.  
  135. None known at this time.
  136.  
  137.  
  138. CAUTIONS
  139. --------
  140.  
  141. Resize
  142. ------
  143. At present I'm generating a resize callback for each set of windows so
  144. that the app can resize the viewport, for instance.  However you won't
  145. get an expose/redraw on the inactive window.
  146.  
  147. Two window implementation
  148. -------------------------
  149. This implementation uses two different windows for single and double
  150. buffering.  If auxiliary windows are used (i.e.  overlays, popups)
  151. they will also be duplicated, with a set parented off the double
  152. buffer window and another set off the single buffer window.
  153.  
  154. When a buffering mode switch occurs the core X window in the widget is
  155. swapped.  This is done so that event handlers transparently switch to
  156. the new GL window.  The only way to get around this switch is to
  157. figure out a portable way to switch buffering modes within one window
  158. which hasn't worked out yet.
  159.  
  160. This core window switch may cause problems in the following areas:
  161.  
  162. 1.    If you get and save the core X window and try to use it when
  163.     it is not active.  Using XtWindow will always return the
  164.     correct core window and is highly recommended.
  165.  
  166. 2.    This implementation hasn't been tested with X children
  167.     attached to the GLX widget.  I don't think this is common
  168.     practice since windows are usually parented off of the window
  169.     above the GLX widget.  When time permits I will work on
  170.     reparenting children so this will work.
  171.  
  172. Colormaps
  173. ---------
  174. The resource GlxNoverrideColormap controls the behavior of installing
  175. colormaps at instantiation time.  It is rather confusing how it works,
  176. though it works the same for this widget as for the standard GlxDraw
  177. and GlxMDraw widgets.
  178.  
  179. By default GlxNoverrideColormap is set to TRUE.  This means that the
  180. colormap provided in the GLXconfig structure (returned when the widget
  181. calls GLXgetconfig) will override the default colormap (which is
  182. usually from the parent).
  183.  
  184. If the application wants to provide its own colormap at instantiation
  185. time, it must set XtNcolormap to this colormap and set
  186. GlxNoverrideColormap to FALSE.
  187.  
  188. When creating the single and double buffered widget, the application
  189. must also set the colormap for GlxNaltColormap, which will be used for
  190. the secondary window.
  191.  
  192. HINTS:  If the application wants to use their own colormaps, it is
  193. usually desireable to find out what visuals will be assigned when the
  194. widget is realized.  The application can find this out by calling
  195. GLXgetconfig itself.  GLXgetconfig does nothing but build a table
  196. which is returned to the application with all the values filled in,
  197. rather than just the ones specified by the application.  This table
  198. can be scanned for buffer=GLX_NORMAL and mode=GLX_COLORMAP to find out
  199. the colormap that will be assigned and buffer=GLX_NORMAL and
  200. mode=GLX_VISUAL to find out the visual that will be assigned.  By
  201. changing the value of buffer=GLX_NORMAL and mode=GLX_DOUBLE, the same
  202. information can be determined for the secondary window.
  203.  
  204.  
  205. NEW RESOURCES
  206. -------------
  207.  
  208. The following lists and describes the new resources provided with this
  209. new version of the GLX widget:
  210.  
  211. GlxNprovideSingleBuffer
  212.     Class = GlxCProvideSingleBuffer
  213.     Type  = XtRBoolean
  214.  
  215.     This resource is used only on instantiation of the widget.  It
  216.     indicates whether both a double buffered and single buffered
  217.     window are required.
  218.  
  219.     WARNING: If set to TRUE, be sure that the GLXconfig structure
  220.     requests a single buffered window.  Also, see the description
  221.     for GlxNaltColormap below.
  222.  
  223. GlxNmainWindow
  224.     Class = GlxCWindow
  225.     Type  = XtRWindow
  226.  
  227.     This resource is filled with the window ID of the primary window.
  228.  
  229. GlxNsingleBuffer
  230.     Class = GlxCSingleBuffer
  231.     Type  = XtRBoolean
  232.  
  233.     This resource identifies which window is currently mapped.  If
  234.     TRUE, the single buffered window is mapped.  It is also used to
  235.     set which window is to be mapped, using XtSetValues.
  236.  
  237. GlxNaltColormap
  238.     Class = GlxCColormap
  239.     Type  = XtRColormap
  240.  
  241.     This resource contains the colormap of the secondary window.
  242.     After instantiating the widget, it will be filled with the
  243.     colormap.  If the application wants to set the colormap for the
  244.     secondary window, this needs to be set to the colormap ID for the
  245.     secondary window.
  246.  
  247.     WARNING: To have this entry paid attention to, the resource
  248.     GlxNoverrideColormap must be set to FALSE (default is TRUE).  If
  249.     this is done, the core colormap (XtNcolormap) must also be set
  250.     with a colormap for the primary window.
  251.